<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Bimaps with user defined names</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Bimap">
<link rel="up" href="../the_tutorial.html" title="The tutorial">
<link rel="prev" href="useful_functions.html" title="Useful functions">
<link rel="next" href="unconstrained_sets.html" title="Unconstrained Sets">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="useful_functions.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_bimap.the_tutorial.bimaps_with_user_defined_names"></a><a class="link" href="bimaps_with_user_defined_names.html" title="Bimaps with user defined names">Bimaps
      with user defined names</a>
</h3></div></div></div>
<p>
        In the following example, the library user inserted comments to guide future
        programmers:
      </p>
<p>
        <a href="../../../../example/user_defined_names.cpp" target="_top">Go to source code</a>
      </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
    <span class="identifier">multiset_of</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;,</span>
    <span class="keyword">int</span>

<span class="special">&gt;</span> <span class="identifier">People</span><span class="special">;</span>

<span class="identifier">People</span> <span class="identifier">people</span><span class="special">;</span>

<span class="comment">// ...</span>

<span class="keyword">int</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span> <span class="special">&gt;&gt;</span> <span class="identifier">user_id</span><span class="special">;</span>

<span class="comment">// people.right : map&lt;id,name&gt;</span>

<span class="identifier">People</span><span class="special">::</span><span class="identifier">right_const_iterator</span> <span class="identifier">id_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">user_id</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">id_iter</span> <span class="special">!=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="comment">// first  : id</span>
    <span class="comment">// second : name</span>

    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
              <span class="special">&lt;&lt;</span> <span class="string">"id:   "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">first</span>  <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Unknown id, users are:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

    <span class="comment">// people.left : map&lt;name,id&gt;</span>

    <span class="keyword">for</span><span class="special">(</span> <span class="identifier">People</span><span class="special">::</span><span class="identifier">left_const_iterator</span>
            <span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span>
            <span class="identifier">iend</span>      <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span>

         <span class="identifier">name_iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">name_iter</span> <span class="special">)</span>
    <span class="special">{</span>
        <span class="comment">// first  : name</span>
        <span class="comment">// second : id</span>

        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">first</span>  <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
                  <span class="special">&lt;&lt;</span> <span class="string">"id:   "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
<span class="special">}</span>
</pre>
<p>
      </p>
<p>
        In Boost.Bimap there is a better way to document the code and in the meantime
        helping you to write more maintainable and readable code. You can tag the
        two collections of the bimap so they can be accessed by more descriptive
        names.
      </p>
<p>
        <span class="inlinemediaobject"><img src="../../images/bimap/tagged.png" alt="tagged"></span>
      </p>
<p>
        A tagged type is a type that has been labelled using a tag. A tag is any
        valid C++ type. In a bimap, the types are always tagged. If you do not specify
        your own tag, the container uses <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">left</span></code>
        and <code class="computeroutput"><span class="identifier">member_at</span><span class="special">::</span><span class="identifier">right</span></code> to tag the left and right sides respectively.
        In order to specify a custom tag, the type of each side has to be tagged.
        Tagging a type is very simple:
      </p>
<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">a_tag</span> <span class="special">&gt;</span> <span class="identifier">tagged_int</span><span class="special">;</span>
</pre>
<p>
        Now we can rewrite the example:
      </p>
<p>
        <a href="../../../../example/user_defined_names.cpp" target="_top">Go to source code</a>
      </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">id</span>   <span class="special">{};</span> <span class="comment">// Tag for the identification number</span>
<span class="keyword">struct</span> <span class="identifier">name</span> <span class="special">{};</span> <span class="comment">// Tag for the name of the person</span>

<span class="keyword">typedef</span> <span class="identifier">bimap</span>
<span class="special">&lt;</span>
                 <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span>        <span class="special">,</span> <span class="identifier">id</span>   <span class="special">&gt;</span>  <span class="special">,</span>
    <span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">name</span> <span class="special">&gt;</span> <span class="special">&gt;</span>

<span class="special">&gt;</span> <span class="identifier">People</span><span class="special">;</span>

<span class="identifier">People</span> <span class="identifier">people</span><span class="special">;</span>

<span class="comment">// ...</span>

<span class="keyword">int</span> <span class="identifier">user_id</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span> <span class="special">&gt;&gt;</span> <span class="identifier">user_id</span><span class="special">;</span>

<span class="identifier">People</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span> <span class="identifier">id_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;().</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">user_id</span><span class="special">);</span>
<span class="keyword">if</span><span class="special">(</span> <span class="identifier">id_iter</span> <span class="special">!=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">()</span> <span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
              <span class="special">&lt;&lt;</span> <span class="string">"id:   "</span> <span class="special">&lt;&lt;</span> <span class="identifier">id_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;()</span>   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Unknown id, users are:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

    <span class="keyword">for</span><span class="special">(</span> <span class="identifier">People</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span>
            <span class="identifier">name_iter</span> <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;().</span><span class="identifier">begin</span><span class="special">(),</span>
            <span class="identifier">iend</span>      <span class="special">=</span> <span class="identifier">people</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;().</span><span class="identifier">end</span><span class="special">();</span>

        <span class="identifier">name_iter</span> <span class="special">!=</span> <span class="identifier">iend</span><span class="special">;</span> <span class="special">++</span><span class="identifier">name_iter</span> <span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"name: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">name</span><span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
                  <span class="special">&lt;&lt;</span> <span class="string">"id:   "</span> <span class="special">&lt;&lt;</span> <span class="identifier">name_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">id</span><span class="special">&gt;()</span>   <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
<span class="special">}</span>
</pre>
<p>
      </p>
<p>
        Here is a list of common structures in both tagged and untagged versions.
        Remember that when the bimap has user defined tags you can still use the
        untagged version structures.
      </p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Left</span>  <span class="special">{};</span>
<span class="keyword">struct</span> <span class="identifier">Right</span> <span class="special">{};</span>
<span class="keyword">typedef</span> <span class="identifier">bimap</span><span class="special">&lt;</span>
         <span class="identifier">multiset_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">Left</span>  <span class="special">&gt;</span> <span class="special">&gt;,</span>
    <span class="identifier">unordered_set_of</span><span class="special">&lt;</span> <span class="identifier">tagged</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">Right</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">bm_type</span><span class="special">;</span>

<span class="identifier">bm_type</span> <span class="identifier">bm</span><span class="special">;</span>

<span class="comment">//...</span>

<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">iterator</span>       <span class="identifier">iter</span>       <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span>  <span class="identifier">left_iter</span>  <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
<span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_iterator</span> <span class="identifier">right_iter</span> <span class="special">=</span> <span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span><span class="special">.</span><span class="identifier">begin</span><span class="special">();</span>
</pre>
<div class="table">
<a name="boost_bimap.the_tutorial.bimaps_with_user_defined_names.t0"></a><p class="title"><b>Table 1.3. Equivalence of expressions using user defined names</b></p>
<div class="table-contents"><table class="table" summary="Equivalence of expressions using user defined names">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Untagged version
                </p>
              </th>
<th>
                <p>
                  Tagged version
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">left</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">right</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_map</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_value_type</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;::</span><span class="identifier">value_type</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">left_iterator</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;::</span><span class="identifier">iterator</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm_type</span><span class="special">::</span><span class="identifier">right_const_iterator</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">::</span><span class="identifier">map_by</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;::</span><span class="identifier">const_iterator</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">left</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">right</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">first</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">second</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">left_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">first</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">second</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">right_iter</span><span class="special">-&gt;</span><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;()</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_left</span><span class="special">(</span><span class="identifier">iter</span><span class="special">)</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project</span><span class="special">&lt;</span><span class="identifier">Left</span><span class="special">&gt;(</span><span class="identifier">iter</span><span class="special">)</span></code>
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project_right</span><span class="special">(</span><span class="identifier">iter</span><span class="special">)</span></code>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">bm</span><span class="special">.</span><span class="identifier">project</span><span class="special">&lt;</span><span class="identifier">Right</span><span class="special">&gt;(</span><span class="identifier">iter</span><span class="special">)</span></code>
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2012 Matias Capeletto<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="useful_functions.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../the_tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="unconstrained_sets.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
